Text file format description
----------------------------

PatchROM text files are usually generated by using PatchROM to dump a script.
While you are probably most interested in editing the strings, you may want
to know about the special commands appearing at the top of the file.

As with all PatchROM files, a comment starts with a semi-colon (;) and runs
to the end of the line.

The first command in the PatchROM text file is usually "load <fontfile>".
This specifies the font definition file to use. As of version 0.70, this
can be a Thingy table or a PatchROM font definition file.

The second command is usually "textaddress <address> [size]". This specifies
the address where the first byte of the first string will be written to the
ROM. If size is present, the entire file will be encoded, and the encoded
block size will be compared to size.  If the encoded block is larger, PatchROM
will NOT save the changed ROM and output and error message.  This prevents
string data from overflowing into other data or even into code.

The next few command describe the pointer table. These are not required, but
most ROMS use a pointer table to access the strings. If you find your ROM only
displaying the last part of your strings, it's probably because the pointer
table hasn't been properly updated.

For standard (contiguous) pointers, (the entire pointer address appears in
one, two, or three bytes in one place), the following should be present:

   pointertable <address>
      Specifies the location of the pointer table. Must be accompanied by
      pointersize.

   pointersize <address>
      Specifies the size of each pointer (in bytes) placed into the pointer 
      table.

For non-standard (broken) pointers, (the low byte of a pointer address
appears in one table, and the high byte appears in another), the following
should be present:

   pointerlow <address>
      Specifies the location of the table for the low pointer byte.

   pointerhigh <address>
      Specifies the location of the table for the high pointer byte. Must be
      accompanied by pointerlow.

   pointerbank <address>
      Specifies the location of the table for the bank pointer byte. Must be
      accompanies by pointerlow and pointerhigh.

For both pointer tables, the number of strings between pointers needs to be
known.  This is done with the "pointerfrequency <number>" command. The first 
pointer will be output for string 0, then every <number> strings thereafter.

By default, PatchROM assumes that the pointer is an offset from the text
address (the text address is added to the pointer value). To specify that
the pointers actually contain the address of the string, use the 
"firstpointer <address>" command. PatchROM will then add <address> to each
offset it calculates before writing the pointer to the pointer table.

The text data begins as soon as PatchROM sees an ID. An ID is a four
character string enclosed in bracket. When dumping, PatchROM outputs the
hex code for the current string index.  

NOTE: because IDs are four character strings enclosed in brackets, PatchROM
does not directly support two byte hexcodes in the text to be encoded -
[3F00] bad, [3F][00] good. This also prevents possible endian confusion.

Once PatchROM encounters the text data, anything that is not a comment or
string ID is encoded. Because comments start with a semi-colon, if your
character set has a semi-colon character, you'll have to put its hex code
into the text (i.e. '[53]' not ';'), or PatchROM will think it's a comment.

By allowing comments within the text to encode, you can leave yourself
messages like '; TODO: better translation'. But the real benefit of having
comments within the text to encode is the dumper actually puts the original
text in a comment, so you can see both the original and the patched string
at the same time.

NOTE: the encoder strips any extra whitespace from the end of a line and
the end of a string. If you need spaces at the end of a line, PatchROM
converts all underscores (_) to spaces. If you need extra new lines at the
end of a string, you'll have to use the hex code for the new line character.
_______________

   ; Sample text patch file
  
   load "font.txt"           ; The character table is stored in font.txt
   textaddress 24800h (312)  ; The text starts at byte 24800h of the ROM file
                             ; and runs for 312 bytes.
   pointertable    24300h    ; The pointer table starts at byte 24300h of the
   pointerfrequency    1     ; ROM file and has an entry for every string.
   pointersize         2     ; Two bytes are output for every offset
   firstpointer     C300h    ; Add 8000h to all pointers. The first pointer
                             ; output would be C300h (address + offset), the 
                             ; next would be C306h (if the first text block 
                             ; was 6 bytes) rather than 0000h and 0006h (default)

   [0000]                    ; IDs are not actually evaluated - this is a                   
   Hello                     ; convenience for the user for identifying a
                             ; string by it's number. They are also required
                             ; to distinguish between strings.

   [0001]                    ; Since pointer frequency is one, string 1 will
   Hello                     ; actually point at string 0 - saving 6 bytes in
                             ; the patched ROM.

   [0002]
   This is an example of a   ; newline character inserted here
   really long string that   ; another one inserted here
   might appear.<pause>      ; section break (<pause> command), newline
   This is still the same    ; newline inserted
   string.                   ; no newline inserted, end of string

   [0003]                    ; String 3 is an empty string. 

   [0004]
   Does this string create   ; Because <yesno> is defined as a terminal, the
   an end of string code     ; end of string code is not appended after the
   here?<yesno>lost data     ; string. In fact, "lost data" will not be stored
                             ; because the converter stops at terminals.
   [0005]                    ; Otherwise, "lost data" would be the fifth 
   This is string 5.         ; string, and "This is string 5." would be the
                             ; sixth

                             ; end of file - converter checks text block size
                             ; against max block size and saves the changes.
_______________

   This document last modified on 9/25/2000 by Brian Weiss